/**
 * \addtogroup FMRadio FM Radio API
 * @{
 *  This file specifies the Samsung FM Radio API for Windows Mobile 
 *  devices.
 *
 *  The FM Radio API controls the phone's FM radio hardware. 
 *
 *  The specific features of the FM Radio vary from device to device.
 *  These are not specified by the Samsung FM Radio API. Please refer to
 *  device-specific documentation for these details.
 *
 * Copyright &copy; 2009 Samsung Electronics
 *   
 * File: smiFMRadio.h
 */

#ifndef _SMI_FMRADIO_H_
#define _SMI_FMRADIO_H_

#include <smiSDK.h>

/**
 *  FM Radio Geographical Region 
 *
 */

typedef enum {
	SMI_FM_RADIO_REGION_USA			,
	SMI_FM_RADIO_REGION_EUROPE		,
	SMI_FM_RADIO_REGION_JAPAN		,
	SMI_FM_RADIO_REGION_SEASIA		,
	SMI_FM_RADIO_REGION_CHINA		
} SmiFMRadioRegion;

/**
 *  Turn On the FM Radio.
 *
 *  @param region [in]		The FM broadcast geographical region.
 * 
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid 
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioTurnOn(SmiFMRadioRegion region);

/**
 *  Turn Off the FM Radio.
 * 
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioTurnOff(void);

/**
 *  Sets the device's FM Radio frequency.
 * 
 *  @param frequency [in]		FM Radio frequency.
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioSetFrequency(DWORD frequency);

/**
 *  Gets the device's current FM Radio frequency.
 * 
 *  @param frequency [out]		FM Radio current frequency.
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioGetFrequency(DWORD *frequency) ;

/**
 *  FM Radio Seek Directions 
 *
 */
typedef enum
{
	SMI_FM_RADIO_SEEK_DIRECTION_UPWARD ,
	SMI_FM_RADIO_SEEK_DIRECTION_DOWNWARD
} SmiFMRadioSeekDirection;


/**
 *  Manually seek upwards or downwards to the FM Radio's next frequency.
 * 
 *  @param direction [in]		Specifies upward or downward.
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioManualSeek(SmiFMRadioSeekDirection direction);

/**
 *  Auto-seek upwards or downwards to the FM Radio's next valid frequency.
 * 
 *  @param direction [in]		Specifies upward or downward.
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioAutoSeek(SmiFMRadioSeekDirection direction);

/**
 *  Scans through all valid frequencies and returns a list of frequencies with a strong broadcast signal.
 * 
 *  @param PresetFreq [out]		Array of frequencies.
 *  @param PresetCount [in]		Maximum number of presets to return. 
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioScan(DWORD *PresetFreq,DWORD PresetCount);

/**
 *  Cancel a frequency scan.
 * 
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioCancelScan(void);

/**
 *  Sets the device's FM Radio volume, in percentage.
 * 
 *  @param Volume [in]			FM Radio volume in percentage.
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the value of the input parameter is not within 0 to 100
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioSetVolume(DWORD Volume);

/**
 *  Gets the device's current FM Radio volume, in percentage.
 * 
 *  @param Volume [out]			FM Radio current volume, in percentage (0-100).
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioGetVolume(DWORD *Volume);

/**
 *  Gets the device's current FM Radio RSSI signal strength.
 * 
 *  @param SigStrength [out]	FM Radio current RSSI signal strength (0-255), 255 being the strongest.
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioGetRSSI(DWORD *SigStrength); 


/**
 *  FM Radio RDS Fields
 *
 */
typedef enum
{
     SMI_FMRADIO_RDS_FIELD_STATIONID 	,
     SMI_FMRADIO_RDS_FIELD_PSNAME 		,
     SMI_FMRADIO_RDS_FIELD_ALTFREQ 		,
     SMI_FMRADIO_RDS_FIELD_PROGTYPE 	
} SmiFMRadioRDSFieldType;


/**
 *  Gets the device's current FM Radio RDS Field.
 * 
 *  @param type [in]			FM Radio RDS Field type.
 *  @param pData [out]			A pointer to the RDS data. This will be set to NULL if the value was deleted.
 *  @param cbData [out]			The number of bytes pointed to by pData. This value will be set to 0 if pData is NULL.
 *
 *  @return 
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiFMRadioGetRDSField(SmiFMRadioRDSFieldType type,PBYTE pData,UINT* cbData);



/**
 *  Pointer to function that handles RDS Field events. The registered field type's current value 
 *  is returned as paramters.
 */ 
typedef void (*SmiFMRadioRDSHandler)(SmiFMRadioRDSFieldType type, BYTE* pData, UINT cbData);

/**
 *   Registers a callback handler to be called whenever the value of the specified field type changes.
 *   A client can only register one handler per process.
 * 
 *   @param type [in]			FM Radio RDS Field type. 
 *   @param handler [in]		Pointer to function that will handle the event.
 *
 *   @return  
 *                              SMI_SUCCESS on success
 *  \n							SMI_ERROR_INVALID_PARAMETER if any input parameter is NULL
 *  \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 */ 
SMI_API SMI_RESULT SmiFMRadioRDSFieldRegisterOnChangeHandler(SmiFMRadioRDSFieldType type, SmiFMRadioRDSHandler handler);


/**
 *  Unregisters the handler registered by a previous call to 
 *  the SmiFMRadioRDSFieldRegisterOnChangeHandler() function.
 *
 *  @param type [in]			FM Radio RDS Field type 
 *  @return  
 *                              SMI_SUCCESS on success
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */  
SMI_API SMI_RESULT SmiFMRadioRDSFieldUnregisterOnChangeHandler(SmiFMRadioRDSFieldType type);

/**
 *  Unregisters all the handlers registered by a previous call to 
 *  the SmiFMRadioRDSFieldRegisterOnChangeHandler() function.
 *
 *  @return  
 *                              SMI_SUCCESS on success
 *  \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */   
SMI_API SMI_RESULT SmiFMRadioRDSFieldUnregisterAllOnChangeHandlers(void);


#endif /* _SMI_FMRADIO_H_ */
/* @} */
